[GitHub]README.mdの目次生成をAction「toc-generator」による自動化で楽しよう

GitHubのリポジトリでとても面倒だったREADME.mdの目次生成を自動で行ってくれるAction「ToC Generator」に触れてみました。

#GitHub

#GitHub Actions

haoyayoi

2020.03.31

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

はじめに

リポジトリのReadme.mdを書き上げた後、読み手が把握しやすい様に目次を追加することがありますが、項目がボリューミーになるとその手間も中々大変なものになります。

それなりにリッチな目次を
ある程度手抜きしつつ
かつ自動的に生成する

の三点が実現出来たら良いなと思っていたところ、バッチリ満たしてくれるActionがありました。設定手順と実行前後の違いについてまとめました。

ToC-Generatorについて

toc-generator/README.ja.md at master · technote-space/toc-generator

目次生成に特化したActionです。動作すると目次生成コミットが積まれます。これ以外の機能はありません。使い方はTOC GeneratorのREADME.mdを一通り読むと判るくらいにシンプルです。

on:
  push:
   - master
jobs:
  comment:
    runs-on: ubuntu-latest
    steps:
      - uses: technote-space/toc-generator@v2
        with:
          GITHUB_TOKEN: ${{ secrets.ACCESS_TOKEN }}

この例は目次生成のみにしていますが、CICDのフローに挟むことも問題ありません。生成した目次はwithにFOLDING: trueを指定することで畳まれるため、長すぎた場合等は設定しておくと親切になると思います。

ToC-Generator実行前

# example 

## description
message

ToC-Generator実行後

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
**Table of Contents**

- [example](#example)
  - [description](#description)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

# example 

## description
message

注意点

触っていたところ嵌った点です。

権限が不足しているとエラーになります

ToC GeneratorのREADME.mdにて、アクションをトリガーしたい場合にはGITHUB_TOKENkeyにPersonalAccessTokenを利用するように書かれていますが、権限が不足しているとエラーで止まります。

GitHub Actions で提供されるGITHUB_TOKENは連続するイベントを作成する権限がありません。したがって、プッシュによってトリガーされるビルドアクションなどは実行されません。これはブランチプロテクションを設定していると問題になる場合があります。もしアクションをトリガーしたい場合は代わりにpersonal access tokenを使用してください。

止まった場合はスコープが不足していないか確認しましょう。repoにチェックを入れることで問題なくなるはずです。